<article class="manual_1" id="install">
<h1>
  <span lang="en">Installation</span>
  <span lang="ja">インストール</span>
</h1>
<p>
<span lang="en">
This chapter introduces the steps to install PG-Strom from the source code.
</span>
<span lang="ja">
本章ではPG-Stromをソースコードからインストールする手順を説明します。
</span>
</p>

<section class="manual_2" id="install-check-list">
<h2>
  <span lang="en">Quick Checklist</span>
  <span lang="ja">チェックリスト</span>
</h2>

<dl>
<dt>
<span lang="en">Server Hardware</span>
<span lang="ja">ハードウェア</span>
</dt>
<dd>
<span lang="en">
It requires generic x86_64 hardware that can run Linux operating system supported by <tt>CUDA Toolkit</tt>.
We have no special requirement for CPU, storage and network devices.
Regarding of RAM capacity, we recommend to installing 150% of RAM towards data size to preload entire data-set onto the shared buffer of <tt>PostgreSQL</tt>.
</span>
<span lang="ja">
CUDA ToolkitのサポートするLinuxオペレーティングシステムを動作可能な x86_64 アーキテクチャのハードウェアが必要です。
CPU、ストレージ、およびネットワークデバイスには特別な要件はありません。
RAMの容量に関しては、データサイズに対して1.5倍の大きさのRAMを搭載する事を推奨します。これは、データセット全体を<tt>PostgreSQL</tt>のshared bufferに事前にロードするために必要です。
</span>
</dd>

<dt>
<span lang="en">GPU devices</span>
<span lang="ja">GPUデバイス</span>
</dt>
<dd>
<span lang="en">
<tt>PG-Strom</tt> requires at least one GPU device on the system, which is supported by <tt>CUDA Toolkit</tt>, has computing capability <tt>3.5</tt> or later; that is corresponding to high-end <tt>Kepler</tt> (like <tt>Tesla K20</tt>), <tt>Maxwell</tt> or <tt>Pascal</tt> generation.
</span>
<span lang="ja">
<tt>PG-Strom</tt>を実行するには少なくとも一個のGPUデバイスがシステム上に必要です。これらは<tt>CUDA Toolkit</tt>でサポートされており、computing capability が<tt>3.5</tt>以降のモデルである必要があります。これは、<tt>Tesla K20</tt>などハイエンドの<tt>Kepler</tt>世代、または<tt>Maxwell</tt>世代、<tt>Pascal</tt>世代に相当します。
</span>
</dd>

<dt>
<span>Operating System</span>
</dt>
<dd>
<span lang="en">
<tt>PG-Strom</tt> requires <tt>Linux</tt> operating system for <tt>x86_64</tt> architecture, and its distribution supported by CUDA Toolkit.
Our recommendation is <tt>Red Hat Enterprise Linux</tt> or <tt>CentOS</tt> version 7.x series.
</span>
<span lang="ja">
<tt>PG-Strom</tt>の実行には、<tt>CUDA Toolkit</tt>によりサポートされている<tt>x86_64</tt>アーキテクチャ向けの<tt>Linux</tt> OSが必要です。推奨環境は<tt>Red Hat Enterprise Linux</tt>または<tt>CentOS</tt>のバージョン7.xシリーズです。
</span>
</dd>

<dt>
<span>PostgreSQL</span>
</dt>
<dd>
<span lang="en">
<tt>PG-Strom</tt> requires <tt>PostgreSQL</tt> version 9.5 or later.
<tt>PostgreSQL</tt> v9.5 newly supports custom scan/join interface that allows extensions to alternate a part of query execution plan with its own implementation.
</span>
<span lang="ja">
<tt>PG-Strom</tt>の実行には<tt>PostgreSQL</tt>バージョン9.5以降が必要です。
<tt>PostgreSQL</tt>v9.5では新たにcustom scan/joinインターフェースがサポートされました。これにより、拡張モジュールがクエリ実行計画の一部または全部を代替する事ができるようになっています。
</span>
</dd>

<dt>
<span>CUDA Toolkit</span>
</dt>
<dd>
<span lang="en">
<tt>PG-Strom</tt> requires <tt>CUDA Toolkit</tt> version 7.0 or later.
<tt>CUDA Toolkit</tt> v7.0 newly supports <tt>NVRTC</tt> (NVIDIA Run-Time Compiler) library that allows software to compile device program then generate GPU binary code on run-time.
<tt>PG-Strom</tt> closely uses this functionality, thus, unavailable to work with older <tt>CUDA Toolkit</tt>.
</span>
<span lang="ja">
<tt>PG-Strom</tt>の実行には<tt>CUDA Toolkit</tt> バージョン7.0以降が必要です。
<tt>CUDA Toolkit</tt> v7.0では新たに <tt>NVRTC</tt> (NVIDIA Run-Time Compiler) ライブラリがサポートされており、これにより、ソフトウェアが実行時にデバイスプログラムをコンパイルし、GPUバイナリコードを生成する事が可能となりました。
<tt>PG-Strom</tt>は本機能に密接に依存しており、それ故、古い<tt>CUDA Toolkit</tt>では動作させる事ができません。
</span>
</dd>
</dl>
</section>

<section class="manual_2" id="install-os">
<h2>
  <span lang="en">OS Installation</span>
  <span lang="ja">OSのインストール</span>
</h2>
<p>
<span lang="en">
Choose a <tt>Linux</tt> distribution that is supported by <tt>CUDA Toolkit</tt>, and then install it according to the installation process of individual distributions.
A list of supported <tt>Linux</tt> distributions is introduced at <a href="http://developer.nvidia.com/" target="_blank">NVIDIA DEVELOPER ZONE</a>.
</span>
<span lang="ja">
<tt>CUDA Toolkit</tt>のサポートする<tt>Linux</tt>ディストリビューションを選択し、個々のディストリビューションのインストールプロセスに従ってインストール作業を行ってください。
<tt>CUDA Toolkit</tt>のサポートする<tt>Linux</tt>ディストリビューションは、<a href="http://developer.nvidia.com/" target="_blank">NVIDIA DEVELOPER ZONE</a>において紹介されています。
</span>
</p>

<p>
<span lang="en">
You may be able to choose the software packages to be installed during the operating system installation.
Source installation of <tt>PostgreSQL</tt> and <tt>PG-Strom</tt> needs software development tool chains below. Please don't forget to install these packages, prior to the next step.
</span>
<span lang="ja">
<tt>PostgreSQL</tt>および<tt>PG-Strom</tt>のソースプログラムからのインストールには、下記のソフトウェア開発ツールが必要となります。次のステップに進む前に、これらのパッケージを忘れずにインストールするようにしてください。
</span>
</p>

<ul>
<li><tt>gcc</tt></li>
<li><tt>make</tt> (GNU make)</li>
<li><tt>git</tt></li>
<li><tt>bison</tt></li>
<li><tt>flex</tt></li>
</ul>

<p>
<span lang="en">
These are usually categorized to development software.
</span>
<span lang="ja">
通常、これらのパッケージは Development Software に分類されています。
</span>
</p>

<p>
<span lang="en">
Also, please don't install the <tt>PostgreSQL</tt> package provided by the distribution, if its package version is prior to 9.5.
</span>
<span lang="ja">
また、ディストリビューションの提供する<tt>PostgreSQL</tt>パッケージのバージョンが9.5以前の場合、これをインストールしないでください。
</span>
</p>

<section class="manual_3" id="install-post-os">
<h3>
  <span lang="en">Post OS installation setting</span>
  <span lang="ja">OSインストール後の設定</span>
</h3>
<p>
<span lang="en">
Once operating system gets installed on your system, a few additional packager configurations are needed for GPU driver installation on the later steps.
</span>
<span lang="ja">
システムへのOSのインストール後、後のステップでGPUドライバをインストールするために、少々のパッケージャー設定が必要です。
</span>
</p>
<p>
<span lang="en">
<tt>DKMS (Dynamic Kernel Module Support)</tt> is a framework that enables to build a Linux kernel module on the fly, according to the Linux kernel currently working on.
NVIDIA's driver supports this framework, and we recommend setup it.
</span>
<span lang="ja">
<tt>DKMS (Dynamic Kernel Module Support)</tt> は、動作中のLinuxカーネル向けのLinuxカーネルモジュールをその場でビルドする事を可能にするフレームワークで、NVIDIAのドライバも対応しています。そのため、我々も<tt>DKMS</tt>のセットアップを推奨します。
</span>
</p>
<p>
<span lang="en">
PRM package of <tt>DKMS</tt> is distributed as a part of Extra Packages for Enterprise Linux (<tt>EPEL</tt>).
So, get <tt>epel-release-&lt;distribution version&gt;.noarch.rpm</tt> from the public FTP site, then install the package.
Once <tt>epel-release</tt> package gets installed, it adds extra configuration of <tt>yum</tt> to pull non-standard packages from the <tt>EPEL</tt> repository.
</span>
<span lang="ja">
<tt>DKMS</tt>パッケージは<tt>EPEL</tt> (Extra Packages for Enterprise Linux) の一部として配布されています。ですので、パブリックFTPサイトから <tt>epel-release-&lt;distribution version&gt;.noarch.rpm</tt> をダウンロードし、これをインストールしてください。
いったん <tt>epel-release</tt> パッケージがインストールされると、<tt>EPEL</tt>リポジトリから非標準のパッケージを入手するための<tt>yum</tt>システムへの設定が追加されます。
</span>
</p>
<p>
<span lang="en">
In addition to the <tt>DKMS</tt>, the following packages are needed to build <tt>nvidia</tt> kernel module. Install them prior to the later steps.
</span>
<span lang="ja">
<tt>DKMS</tt>に加えて、<tt>nvidia</tt>カーネルモジュールをビルドするには以下のパッケージが必要です。以降のステップに進む前に、これらをインストールしてください。
</span>
</p>

<ul>
<li><tt>kernel-devel</tt></li>
<li><tt>kernel-headers</tt></li>
<li><tt>kernel-tools</tt></li>
<li><tt>kernel-tools-libs</tt></li>
</ul>
</section>

<section class="manual_3" id="install-disable-nouveau">
<h3>
  <span lang="en">disables nouveau driver</span>
  <span lang="ja">nouveauドライバの無効化</span>
</h3>

<p>
<span lang="en">
<tt>CUDA Toolkit</tt> needs the official <tt>nvidia</tt> driver provided by NVIDIA. However, it conflicts with <tt>nouveau</tt> driver that is a compatible open source driver. So, you need to disable the <tt>nouvean</tt> driver prior to installation of <tt>CUDA Toolkit</tt>, if OS installer already setup <tt>nouveau</tt> driver.
</span>
<span lang="ja">
<tt>CUDA Toolkit</tt>が動作するためにはNVIDIAの提供する<tt>nvidia</tt>ドライバが必要です。しかし、オープンソースの互換ドライバである<tt>nouveau</tt>と競合してしまうため、OSインストーラが<tt>nouveau</tt>ドライバをインストールしている場合には、<tt>CUDA Toolkit</tt>のインストールに先立って<tt>nouveau</tt>ドライバを無効化する必要があります。
</span>
</p>

<p>
<span lang="en">
Put the following configuration on the <tt>/etc/modprobe.d/blacklist-nouveau.conf</tt>, to prevent loading the <tt>nouveau</tt> driver.
</span>
<span lang="ja">
<tt>nouveau</tt>ドライバがロードされないよう、以下の設定を<tt>/etc/modprobe.d/blacklist-nouveau.conf</tt>に追加します。
</span>
</p>
<pre>
blacklist nouveau
options nouveau modeset=0
</pre>

<p>
<span lang="en">
Then, run <tt>dracut -f /boot/initramfs-$(uname -r).img $(uname -r)</tt>, to update kernel boot image correctly.
</span>
<span lang="ja">
その後、カーネルブートイメージを更新するために <tt>dracut -f /boot/initramfs-$(uname -r).img $(uname -r)</tt> を実行してください。
</span>
</p>

<p>
<span lang="en">
Then, restart the system, using <tt>shutdown -r now</tt> to apply this configuration.
It is successfully configured, if output of <tt>lsmod</tt> contains no <tt>nouveau</tt> entries.
</span>
<span lang="ja">
その後、この設定を反映させるために <tt>shutdown -r now</tt> を実行してシステムを再起動します。
<tt>lsmod</tt>の出力に<tt>nouveau</tt>が含まれていなければ正しく設定されています。
</span>
</p>
<pre>
$ lsmod | grep nouveau
$
</pre>
</section>
</section>

<section class="manual_2" id="install-cuda">
<h2>
  <span lang="en">CUDA Toolkit Installation</span>
  <span lang="ja">CUDA Toolkitのインストール</span>
</h2>
<p>
<span lang="en">
This section introduces the installation of <tt>CUDA Toolkit</tt>.
If you already install the required version of <tt>CUDA Toolkit</tt>, you can skip this section.
</span>
<span lang="ja">
本節では<tt>CUDA Toolkit</tt>のインストールについて説明します。
既に対応バージョンの<tt>CUDA Toolkit</tt>をインストール済みであれば、本節の内容は読み飛ばして構いません
</span>
</p>


<p>
<span lang="en">
NVIDIA provides two types of installation methods for <tt>CUDA Toolkit</tt>; the first is self-executable archive (called as runfile), the other is collection of RPM packages. Our recommendation is RPM installation. <tt>PG-Strom</tt>'s <tt>Makefile</tt> is designed according to the installation layout of RPM packages.
</span>
<span lang="ja">
NVIDIAは<tt>CUDA Toolkit</tt>のインストールに２通りの方法を提供しています。一つは自己実行型アーカイブ（runfileと呼ばれる）によるもの。もう一つはRPMパッケージによるものです。
推奨はRPMインストールであり、<tt>PG-Strom</tt>の<tt>Makefile</tt>もRPMパッケージによるインストールを前提に設計されています。
</span>
</p>
<p>
<span lang="en">
You can download the <tt>CUDA Toolkit</tt> installation package from <a href="https://developer.nvidia.com/cuda-downloads" target="_blank">NVIDIA DEVELOPER ZONE</a>.
Please select proper operating system, architecture, distribution, version and installer type.
RPM installation in this document intends to use "rpm (network)".
</span>
<span lang="ja">
<tt>CUDA Toolkit</tt>のインストール用パッケージは<a href="https://developer.nvidia.com/cuda-downloads" target="_blank">NVIDIA DEVELOPER ZONE</a>からダウンロードする事ができます。
適切なOS、アーキテクチャ、ディストリビューション、バージョン、およびインストータライプを選択してください。
本節におけるRPMインストールは『rpm(network)』の使用を意図しています。
</span>
<div class="figure">
<img src="./figs/cuda-install-target.png">
</div>
</p>

<section class="manual_3" id="install-cuda-rpm">
<h3>
  <span lang="en">RPM installation</span>
  <span lang="ja">RPMインストール</span>
</h3>
<p>
<span lang="en">
The "rpm (network)" package contains only definition of the yum repository that distributes <tt>CUDA Toolkit</tt>. It is similar method when we add definition of the <tt>EPEL</tt> repository on %%%PGSTROM_MANUAL_XLINK:install-os%%%.
So, you need to obtain and install the related RPM packages over the network.
Run the commands below.
</span>
<span lang="ja">
『rpm(network)』パッケージには<tt>CUDA Toolkit</tt>を配布するyumリポジトリの定義情報が含まれているだけです。これは %%%PGSTROM_MANUAL_XLINK:install-os%%% においてシステムに<tt>EPEL</tt>リポジトリの定義を追加したのと同様の方法です。
したがって、<tt>cuda</tt>リポジトリを登録した後、関連したRPMパッケージをネットワークインストールする必要があります。
下記のコマンドを実行してください。
</span>
<pre>
$ sudo rpm -i cuda-repo-&lt;distribution&gt;-&lt;version&gt;.x86_64.rpm
$ sudo yum clean all
$ sudo yum install cuda
</pre>
</p>
<p>
<span lang="en">
Once installation gets completed, <tt>CUDA Toolkit</tt> shall be deployed under the <tt>/usr/local/cuda</tt>.
</span>
<span lang="ja">
正常にインストールが完了すると、<tt>/usr/local/cuda</tt>配下に<tt>CUDA Toolkit</tt>が導入されています。
<pre>
$ ls /usr/local/cuda
LICENSE  bin  extras   lib64      libnvvp  samples  src      tools
README   doc  include  libnsight  nvvm     share    targets
</pre>
</p>
</section>

<section class="manual_3" id="install-cuda-runfile">
<h3>
  <span lang="en">Runfile installation</span>
  <span lang="ja">Runfileインストール</span>
</h3>
<p>
<span lang="en">
The self executable archive, called "runfile", contains full-set of the <tt>CUDA Toolkit</tt>.
Download the runfile, then execute it under the <tt>root</tt> user privillege.
</span>
<span lang="ja">
Runfileと呼ばれる自己実行型アーカイブには<tt>CUDA Toolkit</tt>のフルセットが格納されています。
Runfileのダウンロード後、<tt>root</tt>ユーザの権限でこれを実行してください。
</span>
</p>
<pre>
$ sudo sh cuda_&lt;version&gt;_linux.run
</pre>

<p>
<span lang="en">
The script prompts to answer several questions during installation, please answer "yes" basically. Especially, ensure the toolkit location is <tt>/usr/local/cuda-&lt;version&gt;</tt> and makes a symbolic link to the location on <tt>/usr/local/cuda</tt>.
</p>
<span lang="ja">
インストール中、スクリプトが質問に対して入力を促す場面が何個かありますが、基本的に "yes" と回答するようにしてください。
また、特に<tt>CUDA Toolkit</tt>のインストールパスが<tt>/usr/local/cuda-&lt;version&gt;</tt>である事、このパスに対するシンボリックリンクを<tt>/usr/local/cuda</tt>に作成する事を確認してください。
</span>
</p>

<div class="hint">
<span lang="en">
If build or installation of the <tt>nvidia</tt> got failed, please check required packages are installed and <tt>nouveau</tt> driver is disabled at the %%%PGSTROM_MANUAL_XLINK:install-os%%% section.
Please note that configuration to disable <tt>nouveau</tt> driver is not applied to the bootstrap image unless you don't execute <tt>dracut</tt> script, especially.
</span>
<span lang="ja">
<tt>nvidia</tt>ドライバのビルドやインストールに失敗する場合は、%%%PGSTROM_MANUAL_XLINK:install-os%%%において必要なパッケージが導入されている事、および<tt>nouveau</tt>ドライバが無効化されている事を確認してください。特に<tt>dracut</tt>スクリプトを実行するまでは<tt>nouveau</tt>ドライバの無効化設定が起動イメージに反映されない事に留意してください。</span>
</div>

<h3 id="cuda-post-installation">
  <span lang="en">Post installation configuration</span>
  <span lang="ja">インストール後の設定</span>
</h3>

<p>
<span lang="en">
We have a known problem about linkage of <tt>NVRTC</tt> that is used by <tt>PG-Strom</tt>, on <tt>CUDA-7.0</tt> and <tt>CUDA-7.5</tt>, at least. Add the following configuration as a workaround.
</span>
<span lang="ja">
少なくとも<tt>CUDA-7.0</tt>および<tt>CUDA-7.5</tt>において、<tt>PG-Strom</tt>の使用する<tt>NVRTC</tt>ライブラリのリンケージに関して問題がある事が分かっており、これを回避するため、ワークアラウンドとして以下の設定を行ってください。
</p>い
<pre>
# echo /usr/local/cuda/lib64 > /etc/ld.so.conf.d/cuda-lib64.conf
# ldconfig
</pre>

<p>
<span lang="en">
Once installation of CUDA and <code>nvidia</code> driver gets completed, ensure the GPU devices are ready to use.
The <code>nvidia-smi</code> command will print information about GPU devices installed on the system, like the example below.
</span>
<span lang="ja">
CUDAおよび<code>nvidia</code>ドライバのインストールが完了したら、GPUが正しく認識されている事を確認してください。
<code>nvidia-smi</code>コマンドを実行すると、以下の出力例のように、システムに搭載されているGPUの情報が表示されます。
</span>
</p>

<pre>
$ nvidia-smi
Sat May 14 21:17:35 2016
+------------------------------------------------------+
| NVIDIA-SMI 352.68     Driver Version: 352.68         |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  GeForce GTX 980     Off  | 0000:02:00.0     Off |                  N/A |
| 33%   33C    P0    41W / 180W |     15MiB /  4095MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+
|   1  Tesla K20c          Off  | 0000:04:00.0     Off |                  Off |
| 30%   36C    P0    42W / 225W |     12MiB /  5119MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                       GPU Memory |
|  GPU       PID  Type  Process name                               Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+
</pre>

</section>
</section>

<section class="manual_2" id="install-postgresql">
<h2>
  <span lang="en">PostgreSQL Installation</span>
  <span lang="ja">PostgreSQLのインストール</span>
</h2>
<p>
<span lang="en">
This section introduces the installation of <tt>PostgreSQL</tt> from the source code.
You can skip this section if you already installed required version of <tt>PostgreSQL</tt> on your system.
If your preference is RPM installation, see the %%%PGSTROM_MANUAL_XLINK:install-postgresql-rpm%%% below.
</span>
<span lang="ja">
本節ではソースコードから<tt>PostgreSQL</tt>をインストールについて説明します。
既に対応バージョンの<tt>PostgreSQL</tt>がインストール済みであれば、本節の内容は読み飛ばして構いません。
RPMインストールに関しては、下記の %%%PGSTROM_MANUAL_XLINK:install-postgresql-rpm%%% を参照してください。
</span>
</p>

<p>
<span lang="en">
<tt>PostgreSQL Global Development Group</tt> distributes both source and binary form of the <tt>PostgreSQL</tt> at <a href="http://www.postgresql.org/ftp/source/" target="_blank">http://www.postgresql.org/ftp/source/</a>.
You can choose a tarball of <tt>PostgreSQL</tt> 9.5.0 or later, and download the archive.
</span>
<span lang="ja">
<a href="http://www.postgresql.org/ftp/source/" target="_blank">http://www.postgresql.org/ftp/source/</a>にて、<tt>PostgreSQL Global Development Group</tt>は<tt>PostgreSQL</tt>のバイナリおよびソースコードを配布しています。
<tt>PostgreSQL</tt> 9.5.0以降のtarballを選択し、これをダウンロードしてください。
</span>
</p>

<p>
<span lang="en">
Extract the tarball you downloaded, then run the <code>configure</code> as follows.
You can specify an arbitrary directory on the <code>--prefix</code> option. Ensure <tt>$PATH</tt> environment variable contains the <tt>/path/to/install/bin</tt>.
You can omit <code>--enable-debug</code> and <code>--enable-cassert</code> options. On the other hands, note that <tt>PG-Strom</tt> is a software with short history, thus, people expect these options are valuable to find out or analyze unknown bugs.
</span>
<span lang="ja">
ダウンロードしたtarballを展開し、以下の通り<code>configure</code>スクリプトを実行してください。
<code>--prefix</code>には任意のディレクトリを指定する事ができますが、<tt>/path/to/install/bin</tt>が<tt>$PATH</tt>環境変数に含まれている事を確認してください。
<code>--enable-debug</code>と<code>--enable-cassert</code>は省略する事も可能ですが、<tt>PG-Strom</tt>は歴史の短いソフトウェアであり、これらのオプションは未知のバグを発見・解析するために役立つ事が期待されています。
</span>
</p>
<pre>
$ ./configure --prefix=/path/to/install --enable-debug --enable-cassert
</pre>

<p>
<span lang="en">
Build the source tree as usual.
</span>
<span lang="ja">
いつも通りにソースコードをビルドします。
</span>
</p>
<pre>
$ make -j &lt;num of parallels&gt;
$ sudo make install
</pre>

<p>
<span lang="en">
Ensure <tt>pg_config</tt> is runnable and its path is correct.
</span>
<span lang="ja">
<tt>pg_config</tt>が実行可能であり、パスが正しい事を確認してください。
</span>
</p>
<pre>
$ which pg_config
/usr/local/pgsql/bin/pg_config
$ pg_config --pgxs
/usr/local/pgsql/lib/pgxs/src/makefiles/pgxs.mk
</pre>

<p>
<span lang="en">
<tt>PG-Strom</tt> does not have its own <tt>configure</tt> script because it has to share all the configuration stuff with the target <tt>PostgreSQL</tt>, not to have any inconsistency.
Thus, its build chain relies on the <tt>pg_config</tt> that provides information when <tt>PostgreSQL</tt> was built.
</span>
<span lang="ja">
<tt>PG-Strom</tt>は固有の<tt>configure</tt>スクリプトを持ちません、なぜなら、対象の<tt>PostgreSQL</tt>と全く同一のコンフィグを持つ必要があり、不整合が許されないからです。
したがって、<tt>PG-Strom</tt>のビルドチェインは、<tt>PostgreSQL</tt>がビルドされた時の情報を提供する<tt>pg_config</tt>を全面的に信頼しています。
</span>
</p>

<section class="manual_3" id="install-postgresql-rpm">
<h3>
  <span lang="en">RPM Installation</span>
  <span lang="ja">RPM インストール</span>
</h3>
<p>
<span lang="en">
<tt>PostgreSQL Global Development Group</tt> also provides a yum repository to distribute the latest and supported <tt>PostgreSQL</tt> and related software.
You can install a small package to setup definition of the yum repository, like <tt>EPEL</tt> configuration, and then install <tt>PostgreSQL</tt> and other software.
</span>
<span lang="ja">
最新およびサポート中の<tt>PostgreSQL</tt>と関連ソフトウェアの配布のため、<tt>PostgreSQL Global Development Group</tt>はyumリポジトリを提供しています。
<tt>EPEL</tt>の設定のように、yumリポジトリの設定を行うだけの小さなパッケージをインストールし、その後、<tt>PostgreSQL</tt>やその他のソフトウェアをインストールします。
</span>
</p>
<p>
<span lang="en">
The list of yum repository definition is here: <a href="http://yum.postgresql.org/repopackages.php" target="_blank">http://yum.postgresql.org/repopackages.php</a>.
You can find many repository definitions for each <tt>PostgreSQL</tt> major version and <tt>Linux</tt> distribution. You need to choose one of <tt>PostgreSQL</tt> 9.5 or later on your <tt>Linux</tt> distribution.
</span>
<span lang="ja">
yumリポジトリ定義の一覧は <a href="http://yum.postgresql.org/repopackages.php" target="_blank">http://yum.postgresql.org/repopackages.php</a> です。
<tt>PostgreSQL</tt>メジャーバージョンと<tt>Linux</tt>ディストリビューションごとに多くのリポジトリ定義がありますが、あなたの<tt>Linux</tt>ディストリビューション向けの<tt>PostgreSQL</tt> 9.5以降のものを選択する必要があります。
</span>
</p>
<p>
<span lang="en">
All you need to do are installation of yum repository definition, then install <tt>PostgreSQL</tt> package.
</span>
<span lang="ja">
以下のように、yumリポジトリの定義をインストールし、次いで、<tt>PostgreSQL</tt>パッケージをインストールすれば完了です。
</span>
<span lang="en">
The packages below are needed to build and run PG-Strom.
</span>
<span lang="ja">
PG-Stromのビルドおよび実行には以下のパッケージが必要です。
</span>

<ul>
<li>postgresql95-devel</li>
<li>postgresql95-libs</li>
<li>postgresql95-server</li>
<li>postgresql95</li>
</ul>
</p>

<p>
<pre>
$ sudo rpm -ivh pgdg-redhat95-9.5-2.noarch.rpm
$ sudo yum install postgresql95-server postgresql95-devel
               :
================================================================================
 Package                  Arch        Version                 Repository   Size
================================================================================
Installing:
 postgresql95-devel       x86_64      9.5.1-1PGDG.rhel7       pgdg95      1.7 M
 postgresql95-server      x86_64      9.5.1-1PGDG.rhel7       pgdg95      4.1 M
Installing for dependencies:
 postgresql95             x86_64      9.5.1-1PGDG.rhel7       pgdg95      1.3 M
 postgresql95-libs        x86_64      9.5.1-1PGDG.rhel7       pgdg95      218 k

Transaction Summary
================================================================================
Install  2 Packages (+2 Dependent packages)

Total download size: 7.4 M
Installed size: 32 M
Is this ok [y/d/N]: <bold>y</bold>
               :
Installed:
  postgresql95-devel.x86_64 0:9.5.1-1PGDG.rhel7
  postgresql95-server.x86_64 0:9.5.1-1PGDG.rhel7

Dependency Installed:
  postgresql95.x86_64 0:9.5.1-1PGDG.rhel7
  postgresql95-libs.x86_64 0:9.5.1-1PGDG.rhel7

Complete!
</pre>

<div class="caution">
<span lang="en">
Right now, <tt>PG-Strom</tt> is not distributed from the yum repository.
</span>
<span lang="ja">
現時点では、<tt>PG-Strom</tt>はこのyumリポジトリからは配布されていません。
</span>
</div>
</section>
</section>

<section class="manual_2" id="install-pgstrom">
<h2>
  <span lang="en">PG-Strom Installation</span>
  <span lang="ja">PG-Stromのインストール</span>
</h2>

<section class="manual_3" id="install-pgstrom-getsource">
<h3>
  <span lang="en">Getting the source code</span>
  <span lang="ja">ソースコードの入手</span>
</h3>
<p>
<span lang="en">
You can check out the <tt>master</tt> branch of the Git repository (<a href="https://github.com/pg-strom/devel" target="_blank">https://github.com/pg-strom/devel.git</a>) to get source code of <tt>PG-Strom</tt>.
</span>
<span lang="ja">
<tt>PG-Strom</tt>のソースコードを入手するには、Gitリポジトリ (<a href="https://github.com/pg-strom/devel" target="_blank">https://github.com/pg-strom/devel.git</a>) の<tt>master</tt>ブランチをチェックアウトします。
</span>
</p>
<pre>
$ git clone https://github.com/pg-strom/devel.git pg_strom
Cloning into 'pg_strom'...
remote: Counting objects: 8531, done.
remote: Compressing objects: 100% (14/14), done.
remote: Total 8531 (delta 1), reused 0 (delta 0), pack-reused 8517
Receiving objects: 100% (8531/8531), 6.50 MiB | 3.40 MiB/s, done.
Resolving deltas: 100% (6427/6427), done.
</pre>

<p>
<span lang="en">
By the feature of GitHub, you can also download the latest source tree as a zip file. However, it is not convenient to follow the update of <tt>PG-Strom</tt>, so we don't recommend using the package unless you don't have particular reason; the server cannot connect to the internet for example.
</span>
<span lang="ja">
GitHubの機能により、最新版のソースツリーをZIPファイルとして入手する事もできますが、<tt>PG-Strom</tt>が更新された時の追従が不便ですので、サーバからインターネットに接続できないなどの事情がない限り、あまりお勧めはしません。
</span>
<div class="figure">
<img src="figs/pgstrom-install-download-zip.png" />
</div>
</section>

<section class="manual_3" id="install-pgstrom-build">
<h3>
  <span lang="en">Building the PG-Strom</span>
  <span lang="ja">PG-Stromのビルド</span>
</h3>
<p>
<span lang="en">
The configuration when you build <tt>PG-Strom</tt> has to be strictly identical with the target <tt>PostgreSQL</tt>. For example, if a particular structure would have different layout on <tt>PG-Strom</tt> from the <tt>PostgreSQL</tt> by the configuration on build, it may lead a bug which is hard to find.
Thus, <tt>PG-Strom</tt> has no own configure script; that may produce inconsistency. It uses <tt>pg_config</tt> to reference the configuration of <tt>PostgreSQL</tt> on its build.
</span>
<span lang="ja">
<tt>PG-Strom</tt>をビルドする時のコンフィグは、インストール先の<tt>PostgreSQL</tt>と厳密に一致していなければいけません。例えば、同じ構造体がビルド時のコンフィグにより<tt>PostgreSQL</tt>と<tt>PG-Strom</tt>で異なったレイアウトを持ってしまったとすれば、非常に発見の難しいバグを生み出してしまうかもしれません。
したがって、（一貫性のない状態を避けるため）<tt>PG-Strom</tt>は独自に<tt>configure</tt>スクリプトを走らせたりはせず、<tt>pg_config</tt>を使って<tt>PostgreSQL</tt>のビルド時設定を参照します。
</span>
</p>
<p>
<span lang="en">
Run <tt>make</tt> then <tt>make install</tt> with no extra configuration, if <tt>PATH</tt> environment variable is configured to <tt>pg_config</tt> of the target <tt>PostgreSQL</tt> correctly.
</span>
<span lang="ja">
<tt>pg_config</tt>にパスが通っており、それがインストール先の<tt>PostgreSQL</tt>のものであれば、そのまま<tt>make</tt>、<tt>make install</tt>を実行してください。
</span>
</p>

<pre>
$ which pg_config
/usr/local/pgsql/bin/pg_config
$ pg_config --pgxs
/usr/local/pgsql/lib/pgxs/src/makefiles/pgxs.mk
$ cd pg_strom
$ make
$ sudo make install
</pre>


<div class="hint">
<span lang="en">
Ensure the <tt>pg_config</tt> command kicked by the <tt>make</tt> on the build is really what you intend.
For example, in case when multiple <tt>PostgreSQL</tt> by RPM installation and source installation are mixed, <tt>pg_config</tt> in use will be determined according to the <tt>$PATH</tt> environment variable.
</span>
<span lang="ja">
<tt>make</tt>コマンドを実行した時に、ビルドの過程で呼び出される<tt>pg_config</tt>コマンドが本当にインストール先の<tt>PostgreSQL</tt>のものであるのかどうかを確認してください。
例えば、RPMインストールとソースインストールの<tt>PostgreSQL</tt>が混在しているような状況では、<tt>$PATH</tt>環境変数の値に依存してどちらの<tt>PostgreSQL</tt>ビルド時設定を反映するかが決まります。
</span>
</div>
</section>

<section class="manual_3" id="install-pgstrom-frequent-troubles">
<h3>
<span lang="en">
Frequent Troubles on Build
</span>
<span lang="ja">
ビルド時のよくあるトラブル
</span>
</h3>

<dl>
<dt>
<span lang="en">
<tt>pg_config</tt> was not found
</span>
<span lang="ja">
<tt>pg_config</tt>が見つからない
</span>
</dt>
<dd>
<span lang="en">
Ensure the <tt>$PATH</tt> environment variable whether it contains the directory you installed the binary commands of the target <tt>PostgreSQL</tt>.
It shall be <tt>/usr/local/pgsql/bin</tt> in the default <tt>--prefix</tt> configuration, however, it is not included in the <tt>$PATH</tt> environment variable of default setting on <tt>Red Hat Enterprise Linux</tt> and <tt>Cent OS</tt>.
</span>
<span lang="ja">
環境変数<tt>$PATH</tt>が、インストール先<tt>PostgreSQL</tt>のバイナリコマンドをインストールしたディレクトリを含んでいるかどうか確認してください。
デフォルトの<tt>--prefix</tt>では、これは<tt>/usr/local/pgsql/bin</tt>となりますが、<tt>Red Hat Enterprise Linux</tt>や<tt>Cent OS</tt>のデフォルト設定の<tt>$PATH</tt>環境変数には含まれていません。
</span>
</dd>

<dt>
<span lang="en">
CUDA related files were not found
</span>
<span lang="ja">
CUDA関連ファイルが見つからない
</span>
</dt>
<dd>
<span lang="en">
Ensure whether the symbolic link <tt>/usr/local/cuda</tt> exists and points the proper directory where you installed the <tt>CUDA Toolkit</tt>.
If you installed <tt>CUDA Toolkit</tt> onto the non-default location, override <tt>CUDA_PATH</tt> variable to be supplied to <tt>make</tt> command.
</span>
<span lang="ja">
シンボリックリンク<tt>/usr/local/cuda</tt>が存在し、<tt>CUDA Toolkit</tt>をインストールしたディレクトリを正しく参照しているかどうか確認してください。
もし<tt>CUDA Toolkit</tt>をデフォルト以外の場所にインストールしているのであれば、<tt>make</tt>コマンドに与える<tt>CUDA_PATH</tt>変数を上書きしてください。
</span>
<pre>
$ make CUDA_PATH=/path/to/cuda/installation/base
</pre>
</dd>
</dl>
</section>
</section>

<section class="manual_2" id="post-intall-setup">
<h2>
  <span lang="en">Post Installation Setup</span>
  <span lang="ja">インストール後の設定</span>
</h2>
<p>
<span lang="en">
This section introduces post-installation setup stuffs.
</span>
<span lang="ja">
本章ではPG-Stromインストール後の設定項目について説明します。
</span>
</p>

<section class="manual_3" id="post-install-initdb">
<h3>
  <span lang="en">Database Creation</span>
  <span lang="ja">データベースの作成</span>
</h3>
<p>
<span lang="en">
If you don't create a database cluster, run <tt>initdb</tt> command to create initial database of <tt>PostgreSQL</tt>
</span>
<span lang="ja">
データベースの初期化が済んでいない場合は、<tt>initdb</tt>コマンドを実行して<tt>PostgreSQL</tt>の初期データベースを作成します。
</span>
</p>
<pre>
$ initdb -D /path/to/database
</pre>
</section>

<section class="manual_3" id="post-install-postgresql_conf">
<h3>
<span lang="en">Configuration of postgresql.conf</span>
<span lang="ja">postgresql.confの設定</span>
</h3>
<p>
<span lang="en">
<tt>$PGDATA/postgresql.conf</tt> is a file to descript configuration parameters of <tt>PostgreSQL</tt>.
This section introduces the minimum required configuration to work <tt>PG-Strom</tt>.
</span>
<span lang="ja">
<tt>$PGDATA/postgresql.conf</tt>は<tt>PostgreSQL</tt>の設定パラメータを記述するファイルです。
本節では、<tt>PG-Strom</tt>を動作させるために最低限必要な設定パラメータについて説明します。
</span>
</p>

<dl>
<dt>
<span>shared_preload_libraries</span>
</dt>
<dd>
<span lang="en">
The <tt>PG-Strom</tt> module has to be loaded, by the <tt>shared_preload_libraries</tt> configuration parameter, on startup of the postmaster process. Thus, it is mandatory to put the configuration below.
</span>
<span lang="ja">
<tt>PG-Strom</tt>モジュールは<tt>shared_preload_libraries</tt>パラメータによってpostmasterプロセスの起動時にロードされる必要があります。したがって、以下の設定項目は必須です。
</span>
<pre>
shared_preload_libraries = '$libdir/pg_strom'
</pre>
</dd>

<dt>
<span>shared_buffers</span>
</dt>
<dd>
<span lang="en">
We recommend expanding <tt>shared_buffers</tt> configuration from the default, to the expected amount of the data size for on-memory processing.
<tt>PG-Strom</tt> enables effective query processing with GPU parallelism on CPU intensive workloads. On the other hands, if most of the data to be processed is stored in the magnetic drives, i/o operation shall be the dominance factor, thus, GPU parallelism will not work well.
So, it is preferable to expand the <tt>shared_buffers</tt> to the amount of data size to be processed, and preload the data using <a href="http://www.postgresql.org/docs/devel/static/pgprewarm.html" target="_blank"><tt>pg_prewarm</tt></a>.
</span>
<span lang="ja">
オンメモリ処理が可能となるよう、<tt>shared_buffers</tt>パラメータの設定値を想定されるデータサイズまで拡大する事を推奨します。
<tt>PG-Strom</tt>はCPU中心の負荷をGPUで並列処理する事により効率的なクエリ処理を実現しますが、処理すべきデータの大半が磁気ディスクに格納されているような状況ではストレージからの読み出しが処理全体の支配項となってしまうため、GPUによる高速化効果が得られません。
そのため、最適なパフォーマンスを得るためには<tt>shared_buffers</tt>を処理対象のデータサイズまで拡大し、<a href="http://www.postgresql.jp/document/9.5/html/pgprewarm.html" target="_blank"><tt>pg_prewarm</tt></a>によってデータを事前にロードしておくのが望ましいです。
</span>
<pre>
shared_buffers = 10GB
</pre>
</dd>

<dt>
<span>work_mem</span>
</dt>
<dd>
<span lang="en">
(Even though it depends on the target workloads,) we recommend to expand <tt>work_mem</tt> into multi-gigabytes at least.
Analytic queries tend to consume larger working memory in general, but less concurrency than transactional workloads. So, larger assignment of <tt>work_mem</tt> configuration allows adopting better execution strategy on CPU side also, like quick-sort instead of disk-sort.
</span>
<span lang="ja">
（対象となるワークロードによりますが、）<tt>work_mem</tt>パラメータを少なくとも数GBまでは拡大する事を推奨します。
一般に解析系クエリは多くのメモリを消費しますが、トランザクション系のシステムに比べると同時接続セッション数は非常に少ない傾向にあります。したがって、より大きな<tt>work_mem</tt>設定は、例えばDisk-SortではなくQuick-Sortなど、CPU側においてもより良い実行戦略を採る事を可能にするでしょう。
</span>
<pre>
work_mem = 10GB
</pre>
</dd>
</dl>

<p>
<span lang="en">
See %%%PGSTROM_MANUAL_XLINK:reference_configs%%% for the configuration parameters provided by <tt>PG-Strom</tt>.
</span>
<span lang="ja">
これ以外に<tt>PG-Strom</tt>が提供する設定パラメータについては %%%PGSTROM_MANUAL_XLINK:reference_configs%%% を参照してください。
</span>
</p>
</section>

<section class="manual_3" id="post-install-create-extension">
<h3>
<span lang="en">Creation of PG-Strom related database object</span>
<span lang="ja">PG-Strom関連オブジェクトの作成</span>
</h3>
<p>
<span lang="en">
The prior configuration enables to load <tt>PG-Strom</tt> on startup of <tt>PostgreSQL</tt>, and get ready to use GPU devices installed on the syste.
Once you start <tt>PostgreSQL</tt> using <tt>pg_ctl</tt>, <tt>PG-Strom</tt> generates log messages related to GPU or CUDA, as follows.
(Although it made a warning because of 2 GPU models in different generation...)
</span>
<span lang="ja">
ここまでの設定で、<tt>PostgreSQL</tt>起動時に<tt>PG-Strom</tt>をロードし、システムに搭載されているGPUを使用する準備ができました。
<tt>pg_ctl</tt>コマンドを使用して<tt>PostgreSQL</tt>を起動すると、以下のように<tt>PG-Strom</tt>やGPU、CUDAに関連したログが出力されます。
（ここでは世代の異なる2つのGPUを搭載しているために警告が出力されていますが）
</span>
</p>
<pre>
$ pg_ctl -D /opt/pgsql/data start
server starting
LOG:  PG-Strom version 1.0devel built for PostgreSQL 9.5
LOG:  CUDA Runtime version: 7.5.0
LOG:  NVIDIA driver version: 352.79
LOG:  GPU0 GeForce GTX 980 (2048 CUDA cores, 1253MHz), L2 2048KB, RAM 4095MB (256bits, 3505MHz), capability 5.2
LOG:  GPU1 Tesla K20c (2496 CUDA cores, 705MHz), L2 1280KB, RAM 4799MB (320bits, 2600MHz), capability 3.5
WARNING:  Mixture of multiple GPU device capabilities
LOG:  NVRTC - CUDA Runtime Compilation vertion 7.5
LOG:  database system was shut down at 2016-03-13 21:56:29 JST
LOG:  MultiXact member wraparound protections are now enabled
LOG:  database system is ready to accept connections
LOG:  autovacuum launcher started
</pre>
<p>
<span lang="en"></span>
<span lang="ja">
インストールの最終ステップは、<tt>PostgreSQL</tt>データベースにログオンして、スキーマやSQL関数など<tt>PG-Strom</tt>関連のデータベースオブジェクトを作成する事です。
一連のステップは<tt>PostgreSQL</tt>のExtensionメカニズムにより自動化されているため、ユーザが行う必要があるのは以下のコマンドを実行する事のみです。
</span>
</p>
<pre>
postgres=# CREATE EXTENSION pg_strom;
CREATE EXTENSION
</pre>

<p>
<span lang="en">
You need to run the above commands. Once you run <tt>CREATE EXTENSION pg_strom;</tt> command towards the special database <tt>template1</tt>, the database newly created shall already have <tt>PG-Strom</tt> setup on the initial state.
</span>
<span lang="ja">
全てのデータベースに対して上記のコマンドを実行する必要がありますが、特別なデータベース<tt>template1</tt>に対して一度<tt>CREATE EXTENSION pg_strom;</tt>を実行すれば、今後作成されるデータベースに対しては、初期状態で既に<tt>PG-Strom</tt>用のセットアップが完了した状態になっています。
</span>
</p>
<pre>
template1=# CREATE EXTENSION pg_strom;
CREATE EXTENSION
</pre>

<p>
<span lang="en">
That is all of the installation process of <tt>PG-Strom</tt>
</span>
<span lang="ja">
以上で<tt>PG-Strom</tt>のインストールは完了です。
</span>
</p>
</section>
</section>
</article>
